@pgellert do we want to also mention here about disaster recovery? 🤔

I'm not sure we need to provide topic_metadata_sync_options in context of schema registry shadowing 🤔

Yes, we can remove the topic_metadata_sync_options section here, it's not needed.

Removed in be45498 — the sample now goes straight from client_options to schema_registry_sync_options, and the highlight range is updated to match.

This is false as stated, because we do add 2 new cluster configurations: https://github.com/redpanda-data/redpanda/blob/c153614a6972b0ee9e109ae93dc9d0a9369a1d37/src/v/config/configuration.cc#L3981-L3996

But they are escape hatches / tunables that won't commonly need to be adjusted.

Fixed in be45498 — replaced the claim with the two tunables (schema_registry_sync_memory_bytes, schema_registry_sync_parallelism) and noted the defaults suit most deployments.

mTLS is also supported as an authentication mechanism, in addition to HTTP Basic

Fixed in be45498 — the limitation now lists HTTP basic and mTLS, and the connection section explains mTLS means a client certificate and key in tls_settings instead of auth_options.

In schema definitions:

• rule sets
• metadata tags
  In configs:
• override metadata
• override rule set
• default metadata
• default rule set
• compatibility group (note: not the same as compatibility level)

Documented in be45498 — the validation policy section now lists these (schema definitions: rule sets, metadata tags; configs: override/default metadata and rule sets, compatibility groups), with your note that compatibility groups are not compatibility levels.

Only plain string lists for contexts and subjects is supported

Documented in be45498 — 'The contexts and subjects lists accept literal names only. Wildcard and prefix patterns are not supported.' DRAFT-VERIFY removed.

Yes, we can remove the topic_metadata_sync_options section here, it's not needed.

One nuance here is that only API mode shadowing actually creates a explicit "Schema Registry Sync Task" that shows up in rpk shadow status. Topic mode replication just adds the _schemas topic to the list of topic partitions to shadow, it doesn't create a separate "Schema Registry Sync Task".

Added in be45498 — the tab now notes that only API mode runs as a separate task in the shadow link status, and topic mode is monitored like any other shadow topic.

In API mode, the schemas topic doesn't have to be empty, but the target contexts the link would import (scoped to the mapped contexts based on the source_filter and destination fields) need to be empty.

Ref: redpanda-data/redpanda#31011

Fixed in be45498 — the DRAFT-VERIFY is replaced with a prerequisite: the destination contexts the link replicates into (per source_filter and destination mapping) must be empty, and the rest of the shadow cluster's registry is unaffected.

It's important to call out here that exact mapping needs to be exhaustive, and if the source schema registry has any contexts that are not mapped, that will lead to a failure of the schema syncing task.
We should recommend that people consider setting up a source_scope filter for the mapped source contexts if they expect that other contexts may later be created on the source schema registry that would fail the sync at a future inconvenient time.

Added in be45498 as an IMPORTANT under the exact mapping example: mappings must cover every replicated context, an unmapped context fails the task, and we recommend scoping the source_filter contexts list to the mapped contexts to guard against contexts created later.

Another limitation to add is that there is currently no coordination between topic data replication and the schema registry syncing task, so topic data serialized with Confluent's SerDes format may contain schema IDs on the shadow cluster earlier than those schemas get replicated over.

Added in be45498 as a limitation: topic data replication and schema replication are not coordinated, so records in the Confluent SerDes wire format can arrive before the schema IDs they contain have replicated.

@pgellert what's the impact of this? Users should not attempt to read from topics that rely on SR until SR synced? Or will this cause write or replication errors?

One more to add here: if schema registry contexts are being used, customers must have the schema_registry_enable_qualified_subjects config enabled -- https://docs.redpanda.com/streaming/current/manage/schema-reg/schema-reg-contexts/#prerequisites

Added in be45498 as a prerequisite, with xrefs to the schema_registry_enable_qualified_subjects property reference and the Schema Registry Contexts prerequisites. Noted it's enabled by default.

@pgellert what's the impact of this? Users should not attempt to read from topics that rely on SR until SR synced? Or will this cause write or replication errors?

@pgellert how do the source filters on subjects work in conjunction with context filters? Does the example above really only apply "orders-value" subject in the default context? What about the .prod context?